Chapter 7
Voice Script Editor

The Voice Script Editor is a powerful tool which gives you total control over the way MacComCenter Plus will answer and process incoming calls. With the proper script file, MacComCenter Plus can be configured to differentiate among incoming voice, fax, data or AppleTalk Remote Access (ARA) calls, and handle the calls appropriately.

The Editor uses icons to create a graphical representation (like a flowchart) of how calls will be processed. The Voice Script Editor dialog appears as follows:

On the left is the floating toolbar which contains the call processing commands represented as icons. On the right is the script window. To create a script, drag and drop an icon from the toolbar onto the script window.

Note: In the text below, the term 'Call Processing Command' is used to refer to an event or condition which occurs during an incoming call. A phone call can be broken up into a number of events, for example: (1) Answer Phone, (2) Play Greeting Message, (3) Record a Message, (4) Hang Up. In this case, 4 events occurred during the call. Each event is defined by a MacComCenter 'Call Processing Command' and each command is represented by an 'Icon in the Script Window.

The call processing commands are connected to one another with arrows which control the flow from one command to the next. As each command is processed, it returns a status of either Success or Failure. The arrows which connect the icons together can test the result of the previous command. This capability allows you to branch to different parts of the script depending on whether a command succeeds or fails. There are 2 kinds of arrows available for connecting icons together. Green arrows define the path to take if the command succeeds. Red arrows define the path to take if the command fails.

To connect two commands together, select the Arrow tool (see below), click in the center of an icon in the Script Window and drag a line to the center of the next icon (command) to be processed. By default, Green (Success) arrows are drawn. To create a Red (Failure) arrow, hold the Option key down before drawing the arrow. Each icon can have a single Green arrow, a single Red arrow or both a Green arrow and Red arrow connecting it to the next command (as shown in the example below):

In this example, This user wants to ignore all calls which are answered on Tuesday, but allow the caller to leave a message if it is Wednesday thru Monday. The 'Start' command is processed when the phone is answered. The 'Start' icon is connected to a 'Check Time' icon which the user has configured to test for Tuesdays. If the day is Tuesday, then the command succeeds. If it is Wednesday thru Monday, then the command fails. So, on Tuesday's the Green arrow is followed to the 'Play Message' command which tells the caller to call back later. That 'Play Message' icon is connected to a 'Hang Up' icon and the call is terminated. On Wednesday thru Monday the Red arrow is followed to a 'Play Message' icon which prompts the caller to leave a message. This 'Play Message' icon is connected to a 'Record Message' icon. After recording the message, the 'Hang Up' icon is processed and the call is terminated.

To create a new script, select New from the File menu. To open an existing script, select Open from the File menu. You can change the appearance of the icons in the script window the Use Graphics Icons option under the Scripts menu. Each icon has a unique number assigned to it by the Script Editor. You can view these numbers by selecting the Show Item Numbers option from the Scripts menu. When you complete a script file, select Save from the File menu to store the script on your hard drive.

You can print scripts by going to the File menu and selecting Print. You can also make the Script you are working on the 'Default Script' by selecting Make Default Script from the Scripts menu. The 'Default Script' is the script which is used when MacComCenter Plus answers the phone in Voice and Fax mode.

Voice Script Tools

There are four tools used by the Voice Script Editor to create and modify scripts. The tools appear as follows:

From left-to-right the tools are:

Text tool -- The text tool allows you to add text to the script window. This is useful for documenting scripts.
Pointer tool -- The Pointer tool allows you to select script icons from the list, and drag and drop them onto the script window.
Pick tool -- The Pick tool allows you to select one or more icons in the script window. You can then use the Pointer tool to move the selected icons, or the Delete key to remove the icons.
Arrow tool -- The Arrow tool is used to link one icon to another using an arrow to define the path the script will follow.

Voice Script Commands

The script commands, represented by icons, are used to define tasks in the Voice Script Editor. Each icon represents a different task.

The following section describes each command, its function and how it's configured. When you drag an icon from the toolbar to the Script Window, the icon's configuration dialog will automatically be displayed. You can double-click on an existing icon in the Script Window to open it's configuration dialog.

Note: Every icon configuration dialog contains call processing termination options. These options are Hang Up on Failure and Hang Up on Success. If Hang Up on Failure is selected and the specified task returns Failure, the call will be immediately terminated. This will occur even if a Red arrow path is available from the selected task. If Hang Up on Success is selected and the specified task returns Success, then the call will be immediately terminated. This will occur even if a Green arrow path is available from the selected task.

Start Icon

This icon allows you to configure the initial call processing options. All scripts must contain a 'Start' command. When the Start icon is selected, the following configuration dialog appears:

Select the default voice messages which will be used when the specified action occurs. Use the provided popup menus to select the voice files.

Get Tones Icon

This icon allows you to define how and when recordings will play.

Look for tones for x seconds -- MacComCenter Plus will wait for the specified number of seconds for the tones to be entered by the caller. If the tones are not entered in the allowed time, a Failure status will be returned.

Stop checking after x tones -- Specify the number of tones that MacComCenter Plus will expect to be entered.

Play Beep before looking for tones -- When selected, a beep will be played before MacComCenter Plus will begin waiting for tones.

Play Message Icon

This icon will cause MacComCenter Plus to play a greeting message. When the Play Message icon is selected, the following configuration dialog appears:

Play Options:

Check for Tones while playing -- When selected, the user can enter tones while an audio file is being played.

Play Beep when done -- When selected, a beep will be played after the recording is played.

Message Options:

Play recording -- Specify the audio file that will be played when this task is processed.

If tone equals x then play recording y -- If the specified touchtone key is pressed, the audio file specified in the popup menu will be played.

Play one recording from the following set -- When this option is selected, you can create a list of audio files which can be played with different playing criteria. This option will allow you to create a play list from which MacComCenter will select a message to play. You can specify the message to be played based on what touchtones have been received, based on what the date or time is, based on what day of the week it is or a combination of these criteria. To create a play list, click on the Play one recording from the following list radio button. To edit an entry in the list, double-click on the list item. To add a new message to the list, double-click on the Click Here to Add Recording list item. The following configuration window will be displayed:

[Configuration Window]

Specify the recording to play from the Recording popup menu. Select when you want the message to be played from the When to Play popup menu. If you select Never, the recording will not play. This is a good way to disable a particular message without deleting it from the list. If you select When nothing else matches, then this message will become the default message for the list. The selected message will play if no other message in the list fits the selection criteria. If you select At Specified Date/Time, then you can select the date, time or day of the week when you want the message to play. By default, Select Days is selected. If you want to specify a specific date, choose Select Date from the Select Days popup menu. The following dialog will appear:

[Select Days]

From this dialog, you can select a specific date. Using this option will allow you to specify messages which play on holidays, your birthday or some special occasion. You can also specify a time of day and a touchtone to further define when this message will be played.

Play Beep Icon

This icon allows you to control the playing of a beep tone. When the Play Beep icon is selected, the following configuration dialog appears:

Repeat Beep x times -- Specify the number of times the beep will be played.

Use Standard Beep -- When selected, the standard beep will be played. The standard beep is a 1/3 second tone.

Play this as the Beep -- Use the popup menu to specify an audio file to be used in place of the standard beep.

Record Message Icon

This icon allows you to control the recording of incoming messages. When the Record Message icon is selected, the following configuration dialog appears:

Record Call for x seconds -- Specify the maximum length of an incoming message.

Enable Call Screening -- When selected, this option will cause the callers message to be played through your modem's speaker while it is being recorded.

Play Beep before Recording -- When selected, the caller will hear a beep tone before MacComCenter Plus starts recording their message.

Do Command Icon

This icon causes MacComCenter Plus to perform a particular command depending upon the touchtone key pressed by the caller. When the Do Command icon is selected, the following configuration dialog appears:

The asterisk ('*') is required for each command. Specify the touchtone key which must be pressed by the caller to access the specified functions. During call processing, MacComCenter looks for a '*x' touchtone key combination and then executes that particular command. If this icon return Success (meaning that it detected a command), then further script processing is terminated. This will occur even if a success path is available from the selected task.

Receive Fax Icon

This icon tells MacComCenter Plus to begin receiving a fax. The configuration dialog for this icon has no additional options. Voice call processing always terminates after this icon is executed. This will occur even if a success or failure path is available from the selected task.

Data Mode Icon

This icon tells MacComCenter Plus to switch into data mode. The configuration dialog for this icon has no additional options. This icon will run either ARA or the MCC Terminal application, depending on how the Answer Data option is set in the MessageCenter Preferences Port Settings window. Voice call processing always terminates after this icon is executed. This will occur even if a success or failure path is available from the selected task.

ARA Mode Icon

This icon tells MacComCenter Plus to switch into ARA mode. The configuration dialog for this icon has no additional options. Voice call processing always terminates after this icon is executed. This will occur even if a success or failure path is available from the selected task.

Note: See MacComCenter Plus and ARA later in this chapter for details on using ARA with MacComCenter Plus.

Remote Message Retrieval Icon

This icon tells MacComCenter Plus to begin a Remote Message Retrieval session. The configuration dialog for this icon has no additional options. Voice call processing always terminates after this icon is executed. This will occur even if a success or failure path is available from the selected task. The caller will be prompted for a mailbox ID and Password.

Hang Up Icon

This icon causes MacComCenter Plus to hang up the phone line. The configuration dialog for this icon has no additional options. Voice call processing always terminates after this icon is executed. This will occur even if a success or failure path is available from the selected task.

Goto Icon

Normally, the next icon to be processed is identified by an arrow line connecting the two icons together. This is not always the best way to connect icons, since they may be separated by other parts of the script. The Goto icon provides another method for identifying the next icon to be processed. Goto icons are always paired with Label icons. You can have multiple Goto icons all going to the same Label icon. When the Goto icon is selected, the following configuration dialog appears:

Select a Label Name -- Specify the target Label icon for the selected Goto task. There are 26 labels per script - one for each letter of the alphabet.

Label Icon

This icon is the label which corresponds to a Goto icon. When the Label icon is selected, the configuration dialog shown below appears:

Select a Label Name -- Specify the label name for the selected Label icon. Select a letter from the popup menu to identify this label. There can only be one icon identified with the selected letter

Check Time Icon

This icon allows you to specify time and date limits which will enable subsequent events in the script When the Check Time icon is selected, the following configuration dialog appears:

When the Select Day(s) option is shown, you can click on the day or days you wish to select. When the Select Date option is selected, a monthly calendar will appear, allowing you to specify a specific day in a specific month. The Time from x Until y options allow you to also specify a specific time of day. This command returns a Failure result if the current Date/Time does not match.

Replay Tones Icon

This icon causes MacComCenter Plus to play back a voice description of the touchtone keys the caller has pressed. When the Replay Tones icon is selected, the following configuration dialog appears:

You must record messages for each touchtone digit and then configure each digit by selecting the appropriate recording from the popup menus. The Replay Tones icon replays the touchtones by playing the audio for each touchtone detected.

Introduction Message -- Use the popup menu to specify the message which will be played when the Replay Tones task is accessed. An example message might say: "The touchtones you have pressed are . . ."

Digit 0 thru 9 -- Use the popup menu to specify the audio files used for each digit. These audio files should just be the name of the digit.

Acknowledgment -- When selected, this option will cause the selected audio file to be played after the replay of the callers tones is finished. An example message might say: "Were the tones just played correct? Press 1 if they were correct, or 0 if they were incorrect."

Look for verification after replaying tones -- This option is used in conjunction with the Acknowledgment option. If a 1 is pressed, verification is considered to be passed and the icon returns success. If a 0 is pressed, verification is considered to have failed and the icon returns a Failure status. If no verification is required, the icon return Success.

Call Plug-in

This icon will cause an external plug-in to be loaded and executed. Plug-in's provide a way for Smith Micro to extend the functionality of the call processing scripting without releasing new versions of the Script Editor.

When the Call Plug-in icon is selected, the following configuration dialog appears:

Select the custom code resource from the popup menu. The configuration dialog will change to a plug-in specific configuration dialog. If there are no plug-ins installed, the popup menu will be disabled.

Clear All Tones Icon

This icon will clear all of the tones entered by the caller. The configuration dialog for this icon has no additional options.

Get Mailbox Number Icon

This icon allows MacComCenter Plus to request a voice mailbox identification number for a particular mailbox. When the Get Mailbox Number icon is selected, the configuration dialog shown below appears:

Look for Mailbox number for x seconds -- Specify the number of seconds MacComCenter Plus will wait for the mailbox number to be entered via touchtones.

Play Beep before looking for Mailbox ID -- When selected, a beep will be sent to the caller before MacComCenter Plus begins waiting for the mailbox number to be entered.

Require a Mailbox password -- When selected, MacComCenter Plus will require that the mailbox's password be entered before it can be accessed.

Use default messages for prompts -- When selected, the default message prompts, defined in the Start icon configuration dialog, will be played.

Play Mailbox Greeting if available -- When selected, the mailbox's greeting message will be played. If the mailbox does not have its own individual message, this option will be ignored.

Check Tone Icon

This icon allows MacComCenter Plus to check for a particular touchtone key sequence. This icon would normally follow the Get Tones icon. When the Check Tone icon is selected, the following configuration dialog appears:

Match Any TouchTone -- When selected, this icon will return a Success status if the caller entered any touchtone. The icon will return a Failure status if no touchtones are entered.

Match this TouchTone sequence -- When selected, this icon will return Success only if the caller entered the specified touchtone sequence. If the touchtones do not match, the icon will return a Failure status.

Call Script Icon

This icon causes MacComCenter Plus to call another script file from within the current script. This mechanism allows you to create specific scripts for specific conditions. These specialized scripts are called sub-scripts. Up to ten sub-scripts may be linked together. When the Call Script icon is selected, the following configuration dialog appears:

Run Script -- Use the popup menu to specify the script to be run. Press Open to open the selected script in the Voice Script Editor.

Why would you use sub-scripts ? Suppose you had a company with Personnel, Engineering and Shipping departments. You wanted a voice mail system where the caller would select (via touchtones) one of the departments. The call would then be controlled by the selected departments call processing options. How would you do this ? You could create 4 scripts: A main script which controls the call once the phone was answered and a department specific script which would control the call once the caller selected a department. The department specific sub-scripts would be called from the main script. This makes all of the scripts easier to maintain and modify.

Return Icon

This icon is used at the end of a sub-script invoked via the Call Script icon. It causes MacComCenter Plus to return to the original script file and specifies the return status of the called script. When the Return icon is selected, the following configuration dialog appears:

Return 'Success' status -- When selected, the script will return to the original script, and report a Success.

Return 'Failure' status -- When selected, the script will return to the original script, and report a Failure.

Loop Count Icon

This icon is used to specify the number of times that a particular section of a script file will be repeated. When the Loop Count icon is selected, the following configuration dialog appears:

Number of times thru Loop -- Specify the number of times that the section will be repeated. During a call, each time this icon is processed, it's internal counter is increased by 1. If the counter is greater then the configured loop count, then the icon will return a Failure status. If the counter is less then or equal to the amount specified, then the icon will return Success.

Count exceeded message -- Use the popup menu to select the audio file which will be played when the loop count exceeds the number specified above. This message is optional.

Fax On Demand

This icon is used to configure the MacComCenter 'Fax On Demand' feature. You should read the Fax On Demand documentation in Chapter 4 before creating a Fax On Demand service.

When the Fax On Demand icon is selected, the following configuration dialog appears:

Fax ID prompt message -- Specify the audio message which will prompt the caller to enter an ID for a fax On Demand document.

Fax ID error message -- Specify the audio message which will tell the caller that they have entered an invalid Fax On Demand document ID and that they should try again

Start fax receive msg -- Specify the audio message which will prompt the caller to press Start on his fax machine to start receiving the fax documents.

Wait x seconds for caller to enter a Fax ID -- Specify that amount of time to wait for the caller to enter the ID of a Fax document. Callers MUST terminate a Fax ID with a * touchtone (i.e. if the Fax ID is 12, then the caller must enter 12*). If no ID is entered in the specified time, then the Fax ID error message will play and the caller will be prompted again to enter a Fax ID.

Set Folder containing Fax-On-Demand files -- Each Fax On Demand icon can point to a different folder containing the Fax On Demand documents. This allows you to have separate folders for Sales, Marketing, Engineering, etc. documents. Click on the Set button to designate a Fax On Demand folder for this icon.

Transfer Call

This icon is used to transfer a call to another telephone extension. This feature REQUIRES that the phone switch or Central Office support Flash Hook Call Transfers.

Note: If Flash Hook Call Transfer is not supported, then this Icon will not work.

When the Transfer Call icon is selected, the following configuration dialog appears:

Calls can be transferred to a number specified by a mailbox's Transfer Call options or to a number specified by the Icon's configuration or both. The Mailbox options (if selected) have a higher priority then the Icon's options. Calls may also be transferred only on specific days of the week or at a specific time of day.

Call Transfers are either 'blind' or accepted/rejected, depending on whether the Accept / Reject message is defined. Blind transfers will transfer the call to the destination number and then hang up without waiting for the phone at the destination to be answered. Accept/Reject transfers will wait for the destination to answer and will then play the Accept / Reject message 10 times. The person answering the destination phone needs to enter a '1' touchtone to accept the transfer or a '3' touchtone to reject the call. The Icon fails if the call transfer is rejected or the Date/Time of the call does not match the configured Date/Time or the destination number is busy. The Icon hangs up if the call transfer succeeds.

Use the selected Mailbox's Transfer Call options -- Check this to use the selected mailbox's Call Transfer options if available. Mailbox options override Icon specific Transfer Call options.

If no Mailbox Preferences are available, use the following: -- Check this to use the Icon specific Transfer Call options.

Transfer to phone number: -- Icon specific phone number / extension to transfer the call to

On: -- Icon specific days of the week for transferring calls

Only transfer from: -- Icon specific time of day values for transferring calls

Message to caller -- Optional audio message telling the caller that MacComCenter is transferring the call

Accept / Reject message -- An optional audio message which sets the transfer mode. If this message is not set, then the call is transferred as a 'blind' transfer. If this message is set, then it is played 10 times while MacComCenter waits for the phone at the destination phone number to be answered and for the user at that number to enter a '1' to accept the call or a '3' to reject it.

Transfer failed message -- Optional audio message telling the caller that the call transfer failed.

MacComCenter Plus and ARA

MacComCenter Plus's call discrimination features can be used with ARA 2.x. If you plan on using MacComCenter Plus's call discrimination features to detect an incoming ARA call, you must remove the Serial Port Arbitrator extension from the Extensions folder.

Note: This release of MacComCenter Plus's call discrimination feature does not support ARA 3.0.

To use call discrimination with ARA:

Open the Remote Access Setup Control Panel.
Ensure that ARA is configured to use the same serial port as MacComCenter Plus.
Ensure that the Answer Calls check box is not selected.
Close the Remote Access Setup Control Panel.
When you call your Macintosh to establish an ARA connection, use the following dialing string:

'Your Mac's Phone Number,,,,, *5'

The ",,,,,*5" shown above causes the computer calling into your Macintosh to wait until the greeting message is playing before sending the *5 tones. These tones are processed by the Do Command icon and they tell MacComCenter Plus to switch to ARA mode.

Go to next Chapter

Return to the Contents page

Return to the top of Chapter 7

Chapter 7 Voice Script Editor